POST Audio

Overview

---

The following table contains important information about the POST method for managing the process of uploading an audio.

POST Audio
Method	POST
URL or Endpoint	/api/v1​/projectId​/audios
Headers	Authorization
Parameters	projectId
Body	downloadUrl, callBackUrl, hasDrm, folderId, title, author, enableDuplicateCheck

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Description
projectId	Yes	string	Unique Id of the project.

Request Body

{
  "downloadUrl": "https://example.com/{audioFile}",
  "callBackUrl": "https://example.com/{callbackEndpoint}",
  "hasDrm": true,
  "folderId": 0,
  "title": "{title}",
  "author": "{author}",
  "enableDuplicateCheck": true,
  "uploadFileDetailsId": 0
}

Information about the fields that appear when you type in the request body are displayed in the table below.

Parameter Name	Mandatory	Type	Description
downloadUrl	Yes	string	The source of the audio. For a file uploaded through the Upload API send the upload's requestKey (recommended) or the upload URL returned by the Upload API. Any other public URL is accepted unless the project setting encodeUploadedFilesOnly is on, in which case only a request key or a VP upload URL is accepted, see Uploaded files only.
callBackUrl	No	string	URL for callback after processing
hasDrm	No	boolean	Indicates if DRM is enabled
folderId	No	integer	Identifier of the folder
title	No	string	Title of the audio.
author	No	string	Author of the audio. When the request references an upload and the project setting enforceUploadOwnership is on, it must match the author stored on that upload, see Upload ownership.
enableDuplicateCheck	No	boolean	Determines whether duplicate audios should be disallowed.
uploadFileDetailsId	No	integer	The ID of upload file details, as returned by the Upload API. Still accepted; sending the upload's requestKey in downloadUrl is recommended instead. When both are sent they must point at the same upload.

info

If the "enableDuplicateCheck" field is set to true, the system will check for existing audios with the same content and prevent them from being uploaded again. If set to false or omitted, duplicates will be allowed.

Important: This field should be enabled for both the initial audio upload and any subsequent uploads. If not enabled initially, the system will not perform the duplicate check, and duplicates will be allowed, even if the content is the same. Author-scoped duplicate check: when the project setting enforceUploadOwnership is on, the check only matches an audio that was created with the same author (trimmed, case-insensitive). A request without an author only matches audios created without an author. With the setting off, the check matches any audio of the project with the same source, as before.

Upload ownership

A request references an upload when downloadUrl is the upload's requestKey or the upload URL returned by the Upload API, or when uploadFileDetailsId is sent. Only uploads of the project in the URL are found.

When the project setting enforceUploadOwnership is on (see PATCH Project Settings):

• The author of the request must match the author stored on the referenced upload. The comparison ignores leading and trailing spaces and letter case.
• A request without author that references an upload with an author is a mismatch.
• An upload without an author is not checked.
• A mismatch, an unknown uploadFileDetailsId, an unknown request key, and a downloadUrl and uploadFileDetailsId that point at different uploads all return the same response, so the response cannot be used to find out whether an upload exists:

{
  "success": false,
  "errors": ["UPLOAD_AUTHOR_MISMATCH"],
  "messages": [],
  "result": null,
  "resultInfo": "The referenced upload does not belong to this author.",
  "errorCode": "UPLOAD_AUTHOR_MISMATCH",
  "statusCode": 403
}

When the setting is off, the author is not checked. An unknown reference or a conflicting pair of references returns 400 Bad Request with a descriptive message.

note

The author on the request is compared with the author of the upload, not with the author of the audio. Changing the author of an audio afterwards does not change who may encode from its upload.

Uploaded files only

When the project setting encodeUploadedFilesOnly is on, the request must reference one of the project's uploads as described above. A downloadUrl that is neither a request key nor a VP upload URL is rejected before anything is fetched:

{
  "success": false,
  "errors": ["UPLOAD_REFERENCE_REQUIRED"],
  "messages": [],
  "result": null,
  "resultInfo": "This project only accepts files uploaded through the VP upload API.",
  "errorCode": "UPLOAD_REFERENCE_REQUIRED",
  "statusCode": 400
}

A request key or upload URL that does not resolve to one of this project's uploads (for example another project's upload, or a key that does not exist) passes this check and is rejected as an unknown reference instead: 400 Bad Request with a descriptive message, or 403 UPLOAD_AUTHOR_MISMATCH when enforceUploadOwnership is also on. See Upload ownership.

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "publicId": "{publicId}"
  },
  "resultInfo": null,
  "statusCode": 200
}

Information about the fields that appear when you receive the response are displayed in the table below.

Top-Level Properties

Field Name	Type	Description
success	boolean	If the response is successful it will return true. Otherwise will return false
errors	array[string]	Indicates if there was an error
messages	array[string]	Returns the response message from back-end
result	object	Returns the response object
publicId	string	Unique identifier of the audio
resultInfo	string	Returns extra information about the result
statusCode	integer	Returns the HTTP Status Code

If the action is successful, the service sends back an HTTP 200 or 201 response.

Errors

For information about the errors that are common to all actions, see Common Errors:

• HTTP Status Code 400: Bad Request

  Includes the fixed code UPLOAD_REFERENCE_REQUIRED when the project only accepts uploaded files, see Uploaded files only.

• HTTP Status Code 401: Unauthorized

• HTTP Status Code 403: Forbidden

  Includes the fixed code UPLOAD_AUTHOR_MISMATCH when the project enforces upload ownership, see Upload ownership.

• HTTP Status Code 404: Result Not Found

• HTTP Status Code 500: Internal Server Error

• HTTP Status Code 503: Backend Fetch Failed